/**
* @brief	多功能环形缓冲区
* @file		XxxRingBuffer.h
* @author	何锡斌
* @email	2537274979@qq.com
* @date		2024/02/01
* @version	V1_0_0
* @par		实现功能：
* - 头插/尾插/头取/尾取/仅读不取/是否满/是否有数据/有多少数据/有多少空位/清空；
* - 灵活，满足先进先出(队列)、后进先出(栈)、数据窗口等多种场景需求；
* @par		注意事项：
* - 如果属于临界资源，请自行实现临界保护；
* - 实际有效的环形缓冲区最大长度为注册长度-1；
* - 直接使用插入函数造成环形缓冲区已满是允许数据覆盖的，如果不想出现这种情况，请利用`XxxRingBuffer_IsFull()`与`XxxRingBuffer_HowManyIdle()`结合插入函数自行二次封装；
* - 当消费速度大于生产速度(不会出现数据覆盖)，且尾插头取或头插尾取时，是支持同时插取的(支持一个任务插同时一个任务取)，即虽是临界资源但允许无需临界保护。注意同时插或同时取的任务仅限数量一(禁止多个任务同时插，或多个任务同时取，这时就需要临界保护)；
* @par		修改日志：
* <table>
* <tr><th>日期			<th>版本		<th>作者	<th>更新内容		</tr>
* <tr><td>2024/02/01	<td>V1_0_0		<td>何锡斌	<td>初版发布；		</tr>
* </table>
*/
#ifndef _XXXRINGBUFFER_H_
#define _XXXRINGBUFFER_H_



typedef struct _STR_XxxRingBuffer STR_XxxRingBuffer;			/**< 环形缓冲区类 */


/********************************************函数声明********************************************/
#ifdef __cplusplus
extern "C" {
#endif


/*获取环形缓冲区类的大小(用于申请内存)*/
unsigned char XxxRingBuffer_GetSize(void);
/*注册*/
int XxxRingBuffer_Register(STR_XxxRingBuffer* pRingBuf, unsigned char* pBuf, unsigned int size);
/*注销(由调用者自己回收内存)*/
int XxxRingBuffer_Delete(STR_XxxRingBuffer* pRingBuf);

/*尾插数据*/
int XxxRingBuffer_InsertTail(STR_XxxRingBuffer* pRingBuf, const unsigned char* pWriteBuf, unsigned int size);
/*头插数据*/
int XxxRingBuffer_InsertHead(STR_XxxRingBuffer* pRingBuf, const unsigned char* pWriteBuf, unsigned int size);
/*提取数据(从头部开始取出)*/
int XxxRingBuffer_PickUpHead(STR_XxxRingBuffer* pRingBuf, unsigned char* pReadBuf, unsigned int size);
/*提取数据(从尾部开始取出)*/
int XxxRingBuffer_PickUpTail(STR_XxxRingBuffer* pRingBuf, unsigned char* pReadBuf, unsigned int size);
/*仅读数据(从头部开始读，只读不提取，读全部有效数据)*/
int XxxRingBuffer_OnlyReadHead(STR_XxxRingBuffer* pRingBuf, unsigned char* pReadBuf);
/*仅读数据(从头部开始读，只读不提取，读指定长度数据)*/
int XxxRingBuffer_OnlyReadHead_Len(STR_XxxRingBuffer* pRingBuf, unsigned char* pReadBuf, unsigned int offset, unsigned int size);

/*是否有有效数据*/
unsigned char XxxRingBuffer_IsHaveValidData(STR_XxxRingBuffer* pRingBuf);
/*是否已满*/
unsigned char XxxRingBuffer_IsFull(STR_XxxRingBuffer* pRingBuf);
/*有多少有效数据*/
unsigned int XxxRingBuffer_HowManyData(STR_XxxRingBuffer* pRingBuf);
/*有多少有效空闲位置*/
unsigned int XxxRingBuffer_HowManyIdle(STR_XxxRingBuffer* pRingBuf);
/*清空(复位)环形缓冲区(软件层面上的清空，实际数据内容没有清零)*/
void XxxRingBuffer_Empty(STR_XxxRingBuffer* pRingBuf);


#ifdef __cplusplus
}
#endif
#endif
